home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / borland / prbgi097.zip / FUNCTION.DOC < prev    next >
Text File  |  1992-12-15  |  72KB  |  1,918 lines
  1. #define C_only
  2. #define Pascal_only
  3.  
  4. Documentation of PRINTBGI package (C) Andrzej Resztak 1991,1992,
  5. all rights reserved.
  6.  
  7. To contact the author write to
  8.  
  9.    Andrzej Resztak
  10.    ul. K. Wallenroda 2c/18
  11.    20-607 Lublin
  12.    POLAND
  13.  
  14. or (preferably) to e-mail address:
  15.    Resztak@PLUMCS11.bitnet
  16.  
  17.  
  18.  
  19. ========================================================================
  20.          FUNCTIONS  DETAILS
  21. ========================================================================
  22.  
  23.    Following section will describe in details all functions which
  24. can be found in PRINTBGI package. This package as distributed in
  25. shareware version was developed and tested in LARGE and HUGE memory
  26. models (I suppose they are the modes most graphic programs use)
  27. using BC++ v2.0. To use it in other memory model you may need
  28. full sources of it (available from the author - see REGISTER.DOC).
  29.  
  30.    When it is mentioned that the function returns zero on success and
  31. nonzero on failure it means that one of the following codes may be
  32. returned
  33.    0                       -  success.
  34.    PRT_NO_MEMORY           1
  35.    PRT_WRONG_PARAMETERS    2
  36.    PRT_NOT_INITIALIZED     3
  37.    PRT_IO_ERROR            4
  38.    PRT_ERROR               5
  39.  Occasionally you can get other code returned from standard Borland graphic
  40. functions or write procedure. You may also get returned code from your own
  41. DrawFunc routine if it returns nonzero code.
  42.  
  43.  
  44. All functions can be divided into following categories.
  45.    - Functions used to set various work parameters.
  46.       PRT_Buffer
  47.       PRT_FormFeedNeeded
  48.       PRT_LinkDrivers
  49.       PRT_ReadDrivers
  50.       PRT_RescaleFillPattern
  51.       PRT_Send
  52.       PRT_SetBuffer
  53.       PRT_SetOutName
  54.       PRT_SetMargins
  55.       PRT_SetDriver
  56.        PRT_SetUserPrintFunc
  57.       PRT_SetViewSize
  58.       PRT_SetErrorFunc
  59.       PRT_SetHaltVariable
  60.       PRT_SetOpenFunc
  61.       PRT_SetCloseFunc
  62.       PRT_SetPrinterDrv
  63.       PRT_SetWriteFunc
  64.       PRT_EMSBuffer
  65.       PRT_XMSBuffer
  66.       setcharsize_Pix
  67.       setfillpattern16
  68.    - Functions used to print out the picture
  69.       PRT_End
  70.       PRT_PrintBGI
  71.       and some functions used internally by PRT_PrintBGI
  72.       (use them only if necessary, the preferable method is using
  73.       PRT_PrintBGI which will virtually do all necessary work for you).
  74.          PRT_AllocateBuffer
  75.          PRT_BuildBitMap
  76.          PRT_BufferNeeded
  77.          PRT_closegraph
  78.          PRT_EMSBufferNeeded
  79.          PRT_EndPrt
  80.          PRT_FreeBuffer
  81.          PRT_getpixel
  82.          PRT_initgraph
  83.          PRT_InitPrt
  84.          PRT_installuserdriver
  85.          PRT_PrintBuffer
  86.          PRT_registerfarbgidriver
  87.          PRT_Unregisterfarbgidriver
  88.          PRT_WritePCX
  89.          PRT_XMSBufferNeeded
  90.    - Functions used to get some information about package and current
  91.      settings of miscellaneous parameters.
  92.       getfillpattern16
  93.       PRT_DriverName
  94.       PRT_DriverNo
  95.       PRT_grapherrormsg
  96.       PRT_MaxDriver
  97.       PRT_MaxMode
  98.       PRT_ModeName
  99.       PRT_ModeParms
  100.       PRT_ModeNo
  101.       PRT_Resolution
  102.       PRT_Version
  103.  
  104. Global export variable
  105.    PRT_HaltPrinting
  106.  
  107.  
  108.    Here are all functions listed alphabetically. Specification will begin
  109. with function declaration followed by exact description of all parameters.
  110.  
  111.  
  112.  
  113.    BGI_LoadDriver
  114.    ==============
  115.  
  116. #if   C_only
  117. void far* BGI_LoadDriver( int driverNo, const char far* bgiPath );
  118. #endif   C_only
  119. #if   Pascal_only
  120. Function BGI_LoadDriver( driverNo: integer; bgiPath: string ): pointer;
  121. #endif   Pascal_only
  122.  
  123.    It is internally used function to load BGI driver into RAM memory.
  124. Parameter driverNo specifies driver to be load and bgiPath specifies
  125. where to look for it. It returns pointer to memory at which driver was
  126. loaded or NULL (NIL in pascal) in case of unsuccessful execution.
  127.    Why you may want to use it? O.K. I didn't write any replacement for
  128. Borland's graphic kernel or for BGI drivers. In fact I use their
  129. installuserdriver and registerbgidriver functions to let them know about
  130. using BGI drivers. But there is one limitations. Both above mentioned
  131. functions can be used only if no graphic system is active. So if you
  132. initialized graphic video system already (using BGI_initgraph) and want
  133. to initialize another BGI driver (for printer system example) which
  134. has not been used already I use BGI_LoadDriver function to load
  135. needed driver into memory. And it fails because you are in graphic mode
  136. already and I cannot use either installuserdriver or registerbgidriver.
  137. To avoid such situations you may want to load all needed drivers into
  138. memory before initializing first BGI driver you will use.
  139.  
  140.  
  141.    BGI_installuserdriver
  142.    =====================
  143.  
  144. #if   C_only
  145. int BGI_installuserdriver( const char far *filename,
  146.                            int huge (*detect)(void),
  147.                            int BGIgroup );
  148. #endif   C_only
  149. #if   Pascal_only
  150. Function BGI_installuserdriver( filename: string; detect: pointer,
  151.                            int BGIgroup ): integer;
  152. #endif   Pascal_only
  153.  
  154.    If you want to use "multiples BGI" feature you must use this
  155. function to install any non Borland BGI driver rather than using
  156. standard Borland installuserdriver function. From your point of
  157. view the only difference between them two is that my version
  158. has an extra third parameter which at call should specify
  159. to which group of BGI drivers installed driver belongs. Currently
  160. I divided all BGI drivers to two groups. One deals with
  161. video displays and the other attends to printers.
  162.    You may use symbolic constants Scrn_BGIgroup and Prt_BGIgroup
  163. to define to which group installed BGI driver belongs.
  164.    But note that in current version I ignore BGIgroup parameter.
  165. Also the detect function should be specified as NULL (nil) in current
  166. version for all non video drivers.
  167.    This function returns negative error code on failure and BGI driver
  168. number on success.
  169.  
  170.  
  171.    BGI_ActiveDriverNo
  172.    ==================
  173.  
  174. #if   C_only
  175. int BGI_ActiveDriverNo(void);
  176. #endif   C_only
  177. #if   Pascal_only
  178. Function BGI_ActiveDriverNo: integer;
  179. #endif   Pascal_only
  180.  
  181.    Returns positive number of currently active BGI driver or negative
  182. error code if no BGI driver is active. Note that when you didn't use
  183. BGI_initgraph but standard initgraph function to initialize graphic the
  184. return value will be incorrect.
  185.  
  186.    BGI_initgraph
  187.    =============
  188.  
  189. #define Scrn_BGIgroup 1
  190. #define Prt_BGIgroup  2
  191. #if   C_only
  192. int BGI_initgraph( int far *Driver, int far *Mode,
  193.                               const char far *BGIPath, int BGIgroup );
  194. #endif   C_only
  195. #if   Pascal_only
  196. Function BGI_initgraph( var Driver, Mode: integer;
  197.                         BGIPath: string; BGIgroup: integer );
  198. #endif   Pascal_only
  199.  
  200.    Use it instead of standard initgraph function. The extra parameter
  201. BGIgroup specifies which kind of graphic devices we want to initialize.
  202. You may specify either Scrn_BGIgroup for initializing video display
  203. or PRT_BGIgroup for initializing graphic printer.
  204.    Rather don't use BGI_initgraph directly to initialize printer graphic
  205. mode. Instead please use PRT_initgraph function or even better
  206. PRT_PrintBGI which will do all work for you.
  207.    The system don't have to be in text mode to use BGI_initgraph
  208. function. It's the difference from standard initgraph function.
  209. Before call of standard Borland initgraph function the system
  210. must be in text mode. That is no BGI driver can be active when
  211. invoking standard initgraph function. It implies that you may use
  212. use initgraph only after closegraph, of course except first time.
  213.    When using BGI_initgraph you have no such limitation. If there is
  214. any BGI driver active when you invoke BGI_initgraph it is suspended
  215. and new BGI driver receives control.
  216.  
  217.  
  218.    BGI_closegraph
  219.    ==============
  220.  
  221. #if   C_only
  222. int BGI_closegraph(void);
  223. #endif   C_only
  224. #if   Pascal_only
  225. Function BGI_closegraph: integer;
  226. #endif   Pascal_only
  227.  
  228.    Closes down recently activated BGI driver. If there
  229. were no previous BGI drivers active at last call to BGI_initgraph
  230. it closes down the whole graphic system. Otherwise the BGI driver
  231. active before last call of BGI_initgraph resumes control.
  232.    Returns 0 on success, nonzero on failure.
  233.  
  234.  
  235.    BGI_registerfarbgidriver
  236.    ========================
  237.  
  238. #if   C_only
  239. int BGI_registerfarbgidriver(void far pascal (*driver)(void) );
  240. #endif   C_only
  241. #if   Pascal_only
  242. Function BGI_registerfarbgidriver(driver: pointer): integer;
  243. #endif   Pascal_only
  244.  
  245.  
  246.    BGI_getgraphmode
  247.    ================
  248.  
  249. #if   C_only
  250. int BGI_getgraphmode( int BGIgroup );
  251. #endif   C_only
  252. #if   Pascal_only
  253. int BGI_getgraphmode( int BGIgroup );
  254. #endif   Pascal_only
  255.  
  256.  
  257.    BGI_setgraphmode
  258.    ================
  259. #if   C_only
  260. void BGI_setgraphmode(int mode);
  261. #endif   C_only
  262. #if   Pascal_only
  263. Procedure BGI_setgraphmode(mode: integer);
  264. #endif   Pascal_only
  265.  
  266.  
  267.    BGI_getmodename
  268.    ===============
  269.  
  270. #if   C_only
  271. const char far* BGI_getmodename(int mode);
  272. #endif   C_only
  273. #if   Pascal_only
  274. Function BGI_getmodename(int mode): string;
  275. #endif   Pascal_only
  276.  
  277.  
  278.    BGI_getresolution
  279.    =================
  280.  
  281. #if   C_only
  282. int BGI_getresolution(int far *x, int far*y);
  283. #endif   C_only
  284. #if   Pascal_only
  285. Function BGI_getresolution(var x,y: integer): integer;
  286. #endif   Pascal_only
  287.  
  288.    Assigns to x and y number of points per inch in horizontal and vertical
  289. directions respectively.
  290.    In current release you will never see resolution larger than 178 dpi.
  291. It is relevant to the bug in Borland graphic kernel. It seems that emulation
  292. of arc function (my BGI driver does not contain routine to draw arc and
  293. thus uses Borland arc emulation function) does not store arc start and
  294. end position. So the call to getarccoords returns wrong result for devices
  295. of vertical resolution of 179 dpi or larger. To eliminate this problem
  296. I always inform graphic kernel that device has vertical resolution lower
  297. than 179 dpi. To achieve correct aspect ratio the horizontal resolution
  298. is also decreased accordingly.
  299.  
  300.  
  301.    getfillpattern16
  302.    =================
  303.  
  304. #if   C_only
  305. void getfillpattern16 ( char FAR * upattern );
  306. #endif   C_only
  307. #if   Pascal_only
  308. Procedure GetFillPattern16 ( upattern: FillPatternType );
  309. #endif   Pascal_only
  310.  
  311.    You may use this function to copy 16x16 bit fill pattern set by
  312. setfillpattern16 function into the 32 (!) byte area pointed to by upattern.
  313. This function may be used only when BITIMAGE BGI driver is active, for all
  314. other BGI drivers it will be ignored.
  315.    See also PRT_RescaleFillPattern.
  316.  
  317.  
  318.  
  319.    PRT_AllocateBuffer
  320.    ===================
  321.  
  322. #if   C_only
  323. int PRT_AllocateBuffer ( void );
  324. #endif   C_only
  325. #if   Pascal_only
  326. Function PRT_AllocateBuffer: integer;
  327. #endif   Pascal_only
  328.  
  329.    This function allocates buffer for picture bit image map. It
  330. allocates as much memory as allowed by PRT_SetBuffer but not more than
  331. needed.
  332.    Note that attempt to allocate buffer is performed in the
  333. following order. First it is tried to allocate XMS buffer next EMS and
  334. at last conventional one. It may result in allocating buffer smaller
  335. than available memory (e.g if there is 200k of free conventional memory
  336. and 32k of free EMS memory then 32k EMS buffer will be allocated).
  337. Note also that buffer always fits in one kind of memory. There is no
  338. possibility to create buffer say 200K large containing of 60K of
  339. conventional memory and rest of EMS or XMS memory.
  340. Used internally by PRT_PrintBGI may also be called by user needing
  341. some nonstandard possibilities.
  342.    Returns 0 on success, nonzero on failure.
  343.  
  344.    see also PRT_SetBuffer, PRT_Buffer, PRT_EMSBuffer, PRT_XMSBuffer,
  345. PRT_BufferNeeded, PRT_EMSBufferNeeded, PRT_XMSBufferNeeded.
  346.  
  347.  
  348.    PRT_Buffer
  349.    =============
  350.  
  351. #if   C_only
  352. int PRT_Buffer ( void far *address, long size, int usable )
  353. #endif
  354. #if   Pascal_only
  355. Function PRT_Buffer ( address: pointer; size: longint; usable: integer ):
  356.                     integer;
  357. #endif
  358.    Defines conventional memory buffer for use by the PrintBGI package.
  359.    Parameters:
  360.       usable   :  0 (zero) means not to use conventional memory. Other
  361.                   arguments are in that case ignored (but preferably should
  362.                   also be zero).
  363.       address  :  Address of conventional memory buffer to use or NULL
  364.                   (buffer will be allocated later by other functions of
  365.                   this package).
  366.       size     :  If address is not NULL defines size (in bytes)
  367.                   of the caller allocated buffer.
  368.                   If address is NULL than
  369.                     -   positive value defines maximum number of memory
  370.                         which can be used for the buffer by PrintBGI package.
  371.                     -   negative value defines minimum number of memory left
  372.                         free after buffer allocation.
  373.                     -   zero allows to allocate as much memory as needed for
  374.                         the buffer leaving only absolutely minimum free.
  375.  
  376.    Note that allocating buffer larger than 64Kb (to be precise 64KB-16 bytes)
  377. is a little tricky in Turbo Pascal. Although I done it in documented way
  378. it might not work in future versions of Turbo Pascal ( that is if heap
  379. memory manager will be changed). I can also give you no guarantee it will
  380. work in all circumstances.
  381.    See also PRT_EMSBuffer,PRT_XMSBuffer.
  382.  
  383.    PRT_BufferNeeded
  384.    =================
  385.  
  386. #if   C_only
  387. long PRT_BufferNeeded ( int x1, int y1, int x2, int y2 );
  388. #endif   C_only
  389. #if   Pascal_only
  390. Function PRT_BufferNeeded ( x1,y1,x2,y2: integer ): longint;
  391. #endif   Pascal_only
  392.  
  393.    Returns size of buffer needed to draw picture of specified size on
  394. printer set by PRT_SetDriver. If there exist less free memory than needed
  395. then picture would be drawn in pieces. In that case results of all
  396. functions reading pixel values may be inaccurate.
  397.    XMS buffer requires some more memory to build a picture. Use
  398. PRT_XMSBufferNeeded in that case.
  399.    May be called only after PRT_SetDriver.
  400.    See also PRT_EMSBufferNeeded, PRT_XMSBufferNeeded.
  401.  
  402.  
  403.    PRT_BuildBitMap
  404.    ================
  405.  
  406. #if   C_only
  407. int PRT_BuildBitMap (
  408.                   int far * graphdriver, int far *graphmode,
  409.                                            const char far *pathtodriver,
  410.                   int x1,int y1, int x2,int y2,
  411.                   int ( huge * far Draw)(void far* UserPointer),
  412.                   void far * UserPointer );
  413. #endif   C_only
  414. #if   Pascal_only
  415.    Type DrawType = function DrawFunc(UserPointer:pointer) : integer;
  416. Function PRT_BuildBitMap ( var graphdriver,graphmode: integer;
  417.                         pathtodriver: string;
  418.                         x1,y1,x2,y2: integer;
  419.                         DrawFunc : DrawType,
  420.                         UserPointer: pointer );
  421. #endif   Pascal_only
  422.  
  423. Parameters
  424.    graphdriver,graphmode,pathtodriver - see PRT_initgraph.
  425.    x1,y1,x2,y2 - coordinates of the rectangular area of the whole
  426.                  picture currently being build by the BitImage BGI driver.
  427.                  All requests to read or write outside the specified region
  428.                  will be ignored. Functions reading pixel value from
  429.                  outside of the specified region will always return zero
  430.                  result (without error set).
  431.    DrawFunc    - see PRT_PrintBGI.
  432.    UserPointer - see PRT_PrintBGI.
  433.  
  434.    Initializes BITIMAGE BGI driver by calling PRT_initgraph. Calls
  435. DrawFunc and DOES NOT close down BITIMAGE BGI driver (and does not free
  436. the buffer with created bit image map). This should result in built
  437. (x1,y1,x2,y2) rectangle of bit image map cut from the entire picture.
  438.  
  439.    This function assumes that PRT buffer large enough to contain
  440. (x1,y1),(x2,y2) rectangle was already allocated using PRT_AllocateBuffer
  441. function.
  442.  
  443.    Returns 0 on success, nonzero on failure.
  444.  
  445.  
  446.    PRT_closegraph
  447.    ===============
  448.  
  449. #if   C_only
  450. int PRT_closegraph(void);
  451. #endif   C_only
  452. #if   Pascal_only
  453. Function PRT_closegraph: integer;
  454. #endif   Pascal_only
  455.  
  456.    Closes down the BGI driver which was being used to print the picture out.
  457. In the case of BitImage BGI driver being used this function DOES NOT free
  458. the buffer with created bit image map of the picture. Just you may close
  459. down the BitImage BGI driver and still have buffer with created bit image
  460. map of the picture. It enables you to activate any other BGI driver and
  461. display created pixel map. But remember to free later the buffer calling
  462. PRT_FreeBuffer function.
  463.  
  464.    Returns 0 on success, nonzero on failure.
  465.  
  466.  
  467.    PRT_DriverName
  468.    ===============
  469.  
  470. #if   C_only
  471. int PRT_DriverName ( unsigned driverno, char FAR * FAR* name_ptr  );
  472. #endif   C_only
  473. #if   Pascal_only
  474. Function PRT_DriverName ( driverno: word; var name_ptr: StringPtr ): integer;
  475. #endif   Pascal_only
  476.  
  477.    Assigns to StringPtr pointer pointing to static string containing the name
  478. of driver numbered driverno. The driver name is general name of all printers
  479. supported by the driver or the name of the most common printer from
  480. all supported by it.  It can be used to list user all allowable printers and
  481. let him choose the appropriate one.
  482.    Returns 0 on success, nonzero on failure.
  483.  
  484.  
  485.    PRT_DriverNo
  486.    =============
  487.  
  488. #if   C_only
  489. int PRT_DriverNo ( void );
  490. #endif   C_only
  491. #if   Pascal_only
  492. Function PRT_DriverNo: integer;
  493. #endif   Pascal_only
  494.    Returns current driver number as set by PRT_SetDriver or minus one.
  495.  
  496.  
  497.    PRT_EMSBuffer
  498.    =============
  499.  
  500. #if   C_only
  501. int PRT_EMSBuffer ( int handle, long size, int usable )
  502. #endif
  503. #if   Pascal_only
  504. Function PRT_EMSBuffer ( handle: integer; size: longint; usable: integer ):
  505.          integer;
  506. #endif
  507.    Defines EMS buffer for use by the PrintBGI package.
  508.    Parameters:
  509.       usable   :  0 (zero) means not to use EMS memory. Other arguments are
  510.                   in that case ignored (but preferably should also be zero).
  511.       handle   :  Number of EMM handle to use for the buffer or zero (buffer
  512.                   will be allocated by the package)
  513.       size     :  If handle is nonzero defines amount of memory (in bytes)
  514.                   allocated to that handler by the caller.
  515.                   If handle is zero then
  516.                     -   positive value defines maximum number of memory (which
  517.                         will be rounded down to 16 KB boundary) that can be
  518.                         used for the buffer by PrintBGI package.
  519.                     -   negative value defines minimum number of memory left
  520.                         free after buffer allocation.
  521.                     -   zero allows to allocate as much memory as needed for
  522.                         the buffer leaving only absolutely minimum free.
  523.  
  524.    See also PRT_Buffer,PRT_XMSBuffer.
  525.  
  526.  
  527.    PRT_End
  528.    =======
  529.  
  530. #if   C_only
  531. int PRT_End(void);
  532. #endif
  533. #if Pascal_only
  534. Function PRT_End: integer;
  535. #endif
  536.  
  537.    Finishes the PrintBGI toolkit. Closes down all files used, frees
  538. memory. Usually used before end of the program.
  539.  
  540.  
  541.    PRT_EndPrt
  542.    ==========
  543.  
  544. #if   C_only
  545. int FAR_PROC _PRT__pascal PRT_EndPrt ( int handle );
  546. #endif
  547. #if Pascal_only
  548. Function PRT_EndPrt ( var handle: file ): integer;
  549. #endif
  550.  
  551.    Sends printer ending sequence to the specified handle.
  552. To print it out uses PRT_write function set by PRT_SetWriteFunc routine.
  553.    Note also that my standard PRT_Write function will call PRT_WriteError
  554. function (set by PRT_SetErrorFunc) whenever output error occurs.
  555.    Returns 0 on success, nonzero on failure.
  556. See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
  557. PRT_SetErrorFunc.
  558.  
  559.  
  560.    PRT_FormFeedNeeded
  561.    ==================
  562.  
  563. #if   C_only
  564. int PRT_FUNC  PRT_FormFeedNeeded ( int ffneeded );
  565. #endif
  566. #if Pascal_only
  567. Function  PRT_FormFeedNeeded ( ffneeded: integer ): integer;
  568. #endif
  569.  
  570.    This function informs the printer driver whether to send form feed
  571. command to the printer at the end of picture printing.
  572.    The current setting of form feed option is returned as a function
  573. result.
  574.    If not called the default value is 1 for laser jet printers and
  575. 0 for all others.
  576.  
  577.  
  578.    PRT_grapherrormsg
  579.    ============
  580.  
  581. #if   C_only
  582. char far * FAR_PROC PRT_grapherrormsg ( int errorcode );
  583. #endif
  584. #if Pascal_only
  585. Function PRT_grapherrormsg ( errorcode: integer ): string;
  586. #endif
  587.    Returns pointer to error message associated with errorcode.
  588.  
  589.  
  590.    PRT_FreeBuffer
  591.    ==============
  592.  
  593. #if   C_only
  594. int PRT_FreeBuffer (void);
  595. #endif
  596. #if   Pascal_only
  597. Function PRT_FreeBuffer: integer;
  598. #endif   Pascal_only
  599.  
  600.    Internal procedure freeing the buffer allocated by PRT_AllocateBuffer.
  601. In the case of freeing EMS buffer does not restore EMS mapping to the state
  602. from before PRT_AllocateBuffer. Thus you must be very careful if your
  603. program uses also EMS memory.
  604.    Returns 0 on success, nonzero on failure.
  605.  
  606.  
  607.  
  608.    PRT_getpixel
  609.    =============
  610.  
  611. #if   C_only 
  612. int  PRT_getpixel ( int x, int y );
  613. #endif   C_only
  614. #if   Pascal_only
  615. Function PRT_getpixel ( x,y: integer );
  616. #endif   Pascal_only
  617.  
  618.    Performs the same function as standard Borland getpixel function but with
  619. two differences.
  620.    Parameters x and y are not whole picture relative
  621. but buffer relative. It makes no difference if there is enough memory
  622. for the whole picture. But if there is not enough free memory 
  623. PRT_getpixel(0,0) will return value of first pixel in the buffer
  624. not the first pixel on the virtual screen. What this pixel is at the whole
  625. picture depends on parameters x1 and y1 passed to PRT_SetViewSize.
  626.    The second difference is that if you load ( or link in) the driver
  627. manually you will be able to call this function after closing BITIMAGE BGI
  628. driver (after PRT_closegraph and maybe also after activating another BGI
  629. driver) but, of course before releasing the screen buffer, and unregistering
  630. the driver (see PRT_Unregisterfarbgidriver). If the driver is loaded
  631. automatically (e.g. by PRT_initgraph) it will be deleted by PRT_closegraph
  632. and you MUST NOT use this function in that case when BGI driver is not
  633. active.
  634.  
  635.  
  636.  
  637.    PRT_initgraph
  638.    ==============
  639.  
  640. #if   C_only
  641. int PRT_initgraph( int far * graphdriver, int far *graphmode,
  642.                                                                                
  643.            const char far *pathtodriver 
  644. );
  645. #endif   C_only
  646. #if   Pascal_only
  647. Function PRT_initgraph ( var graphdriver,graphmode: integer;
  648.                          pathtodriver: string ): integer;
  649. #endif   Pascal_only
  650.  
  651. Parameters
  652.    *graphdriver : an integer that specifies graphic driver to be used.
  653.                  Note that earlier you should install BGI driver
  654.                  (currently BitImage driver  only is included into the
  655.                  package) using PRT_installuserdriver function.
  656.                  If you specify DETECT as a passing argument value
  657.                  then the driver last used in PRT_initgraph or last installed
  658.                  using PRT_installuserdriver will be used. If none BGI printer
  659.                  driver was installed so far than PRT_installuserdriver will
  660.                  be called to install appropriate driver for printer defined
  661.                  by PRT_SetDriver. No true auto detection is (or will be)
  662.                  available.
  663.    *graphmode   : an integer that specifies graphic mode to be used.
  664.                  It should be zero value since in current version you
  665.                  must specify desired printing mode using PRT_SetDriver
  666.                  function.
  667.    pathtodriver : Specifies path to BGI drivers and CHR fonts. This parameter
  668.                  will be passed further to standard initgraph routine.
  669.  
  670.  
  671.    Initializes BITIMAGE BGI driver for creating bit image map.
  672. Note that YOU MUST earlier specify rectangular area for which bit map will
  673. be created by calling PRT_SetViewSize function.
  674. All requests for drawing (or reading) pixels outside that
  675. area will be ignored without any error codes. This would enable
  676. building the screen from rectangular pieces and printing it out even if
  677. there is not enough free memory to build the whole bit image map of
  678. printed picture at once.
  679.  
  680.    You must call PRT_SetViewSize before PRT_initgraph.
  681. (x1,y1),(x2,y2) area (specified by PRT_SetViewSize) must fill
  682. entirely within  - PREVIOUSLY - allocated buffer (via PRT_AllocateBuffer),
  683. otherwise an error code is return.
  684.    Returns 0 on success, nonzero on failure.
  685.  
  686.  
  687.    PRT_InitPrt
  688.    ============
  689.  
  690. #if C_only
  691. int FAR_PROC _PRT__pascal PRT_InitPrt ( int handle );
  692. #endif
  693. #if Pascal_only
  694. Function PRT_InitPrt ( var handle: file ): file;
  695. #endif
  696.  
  697.    Sends printer initialization sequence to the specified handle.
  698. To print it out uses PRT_write function set by PRT_SetWriteFunc routine.
  699.    Note also that my standard PRT_Write function will call PRT_WriteError
  700. function (set by PRT_SetErrorFunc) whenever output error occurs.
  701.    Returns 0 on success, nonzero on failure.
  702. See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
  703. PRT_SetErrorFunc.
  704.  
  705.  
  706.    PRT_installuserdriver
  707.    =====================
  708.  
  709. #if   C_only
  710. int PRT_installuserdriver ( const char far * name,
  711.                                             int huge (*detect)(void) );
  712. #endif
  713. #if   Pascal_only
  714. Type DetectFunc = function: integer;
  715. PRT_installuserdriver ( name: string; detect: DetectFunc ): integer;
  716. #endif
  717.  
  718.    Used instead of standard Turbo installuserdriver function. You should
  719. use it to install BitImage BGI driver.
  720.  
  721.  
  722.    PRT_LinkDrivers
  723.    ===============
  724.  
  725. #if   C_only
  726. int PRT_LinkDrivers(void);
  727. #endif
  728. #if   Pascal_only
  729. Function PRT_LinkDrivers: integer;
  730. #endif
  731.  
  732.    Forces linking printers definitions into executable file at linking
  733. time. You must use either PRT_LinkDrivers or PRT_ReadDrivers before
  734. any other function of this toolkit.
  735.    Returns zero on success.
  736.    See also PRT_ReadDrivers.
  737.  
  738.  
  739.    PRT_MaxDriver
  740.    ==============
  741.  
  742. #if   C_only
  743. int PRT_MaxDriver ( void );
  744. #endif   C_only
  745. #if   Pascal_only
  746. Function PRT_MaxDriver : integer;
  747. #endif   Pascal_only
  748.  
  749.    Returns maximum allowed printer driver number in PRINTBGI package
  750. or -1 if there is no printers definitions file.
  751.    Printer drivers are numbered starting from 1. Please do not
  752. use driver number 0. It is intended for future use. Use of it
  753. in current version will give you unpredictable results.
  754.    See also PRT_SetDriver, PRT_DriverName, PRT_DriverNo.
  755.  
  756.  
  757.  
  758.    PRT_MaxMode
  759.    ============
  760.  
  761. #if   C_only
  762. int PRT_MaxMode ( unsigned driverno, int FAR *maxmode );
  763. #endif   C_only
  764. #if   Pascal_only
  765. Function PRT_MaxMode ( printerno: word; var maxmode: integer ): integer;
  766. #endif   Pascal_only
  767.  
  768.    Assigns to maxmode maximum mode number allowed for given driverno.
  769.    Returns 0 on success, nonzero on failure.
  770.    See also PRT_ModeName,  PRT_ModeNo.
  771.  
  772.  
  773.    PRT_ModeName
  774.    =============
  775.  
  776. #if   C_only
  777. int PRT_ModeName ( unsigned driverno, int modeno,
  778.                      char FAR* FAR* name_ptr );
  779. #endif   C_only
  780. #if   Pascal_only
  781. Function PRT_ModeName ( driverno: word; modeno: integer;
  782.                         var name_ptr: StringPtr ): integer;
  783. #endif   Pascal_only
  784.  
  785.    Assigns to StringPtr pointer pointing to static string containing name
  786. of mode modeno and printer numbered driverno. Note that this static area
  787. may be overwritten at next call to any other package function.
  788.    It can be used to list user all allowable modes and let him choose one.
  789.    Returns 0 on success, nonzero on failure.
  790.  
  791.  
  792.    PRT_ModeNo
  793.    ==========
  794.  
  795. #if   C_only
  796. int PRT_ModeNo ( void );
  797. #endif   C_only
  798. #if   Pascal_only
  799. Function PRT_ModeNo: integer;
  800. #endif   Pascal_only
  801.  
  802.    Returns current mode number as set by PRT_SetDriver or negative
  803. value.
  804.  
  805.  
  806.    PRT_ModeParms
  807.    =============
  808.  
  809. #if   C_only
  810. int PRT_ModeParms ( unsigned driverno, int modeno,
  811.                     unsigned far* xRes, unsigned far* yREs,
  812.                     unsigned far* colorsNo  );
  813. #endif   C_only
  814. #if   Pascal_only
  815. Function PRT_ModeName ( driverno: word; modeno: integer;
  816.                         var xREs,yREs,colorsNO: word ): integer;
  817. #endif   Pascal_only
  818.  
  819.    Assigns to xRes and yRes number of dots per inch in horizontal and
  820. vertical directions respectively. To colorsNo assigns number of colors
  821. available in mode modeno for driver driverno.
  822.    Returns 0 on success, nonzero on failure.
  823.  
  824.  
  825.  
  826.  
  827.    PRT_PrintBGI
  828.    =============
  829.  
  830. #if   C_only
  831. int far PRT_PrintBGI ( int far * graphdriver, int far *graphmode,
  832.                                                      const char far 
  833. *pathtodriver,
  834.                        int ( huge * far  /* pascal */ Draw)
  835.                            (void far* UserPointer),
  836.                        void far* UserPointer );
  837. #endif   C_only
  838. #if   Pascal_only
  839.    Type DrawType = function DrawFunc(UserPointer: pointer): integer;
  840. Function PRT_PrintBGI ( var graphdriver,graphmode: integer;
  841.                         pathtodriver: string;
  842.                         DrawFunc : DrawType,
  843.                         UserPointer: pointer );
  844. #endif   Pascal_only
  845.  
  846. Parameters
  847.    graphdriver,graphmode,pathtodriver - see PRT_initgraph.
  848.    Draw        : function drawing picture you want to print.
  849.    UserPointer : This parameter is not used by my library routines
  850.                  and will be passed unchanged to your Draw function.
  851.                  It may point to list of parameters for your Draw
  852.                  function.
  853.  
  854.    This is the main function of the whole package. In fact it does most
  855. of the work and using it is the most recommended way to use the whole
  856. PRINTBGI package. Of course in some nonstandard situations you may
  857. want to use some lower level routines to get more control over the package.
  858. But I think it will be very rarely case.
  859.  
  860.    I'll list all functions it does in the order they are performed.
  861. It should let you better understand other functions of this
  862. package.
  863.  
  864.    So it does the following.
  865.    1. Checks the correctness of arguments used in call to
  866.       PRT_SetDriver. Returns immediately PRT_NOT_INITIALIZED value if
  867.       they are incorrect, otherwise goes to step 2.
  868.    2. Checks if any BGI driver was active when it was called. If it
  869.       was then closes it down and saves information needed to restore
  870.       screen graphic mode. Note that this step (or step 7
  871.       restoring caller graphic mode) may not work  correctly at all
  872.       circumstances (since for example it is very hardly to guess
  873.       what BGI driver was active at call to PRINTBGI).
  874.       So I highly recommend you to close down any BGI drivers you
  875.       were using before calling this function. Note also that
  876.       restorecrtmode function DOES NOT close down BGI driver but
  877.       only deactivates it. So you MUST USE closegraph function rather
  878.       than restorecrtmode before calling PRT_PrintBGI.
  879.    3. Allocates buffer using PRT_AllocateBuffer function.
  880.       If buffer allocation is unsuccessful returns immediately, otherwise
  881.       computes window size filling entirely in the allocated buffer
  882.       and calls PRT_SetViewSize to set it. This window may (or may not)
  883.       cover the whole printing picture.
  884.    4. Calls PRT_Open and PRT_InitPrt to open file handle and to send
  885.       initialization codes to the printer.
  886.    5. Calls PRT_BuildBitMap to create bit image map of current
  887.       rectangular piece of picture which fits into allocated buffer.
  888.       PRT_BuildBitMap is described earlier in this chapter.
  889.    6. Calls PRT_PrintBuffer to print out current buffer ( which now
  890.       contains one piece of picture). If it is not the last
  891.       (or the only one) piece to print returns to point 5.
  892.    7. Calls PRT_EndPrt and PRT_Close;
  893.    8. Calls PRT_closegraph to close down the BGI driver used to create
  894.       bit image map of the printed picture.
  895.    9. Frees allocated buffer by calling PRT_FreeBuffer.
  896.   10. If in step 2 the active BGI driver was closed down tries now to
  897.       reactivate it. Note that it uses standard detectgraph function to
  898.       determine which BGI driver reactivate. So if you had nonstandard
  899.       BGI drivers active (e.g. SVGA or VGA256) it may happen that standard
  900.       VGA driver will be reactivate instead of the actually active one.
  901.       To avoid this problem either close down video BGI driver (using
  902.       closegraph) before calling PRT_PrintBGI or install nonstandard
  903.       BGI drivers with appropriate auto detection function
  904.       (see installuserdriver function in Borland documentation).
  905.       Note also that screen image is not restored.
  906.   11. Returns to the caller.
  907.  
  908.  
  909.    Function DrawFunc passed as an argument should meet the following
  910.    conditions.
  911.       - It draws on the screen the picture you want to print.
  912.       - It does not use any nonstandard graphic procedures (that is not
  913.         defined in GRAPH.TPU or GRAPHICS.LIB) to manipulate screen
  914.         output.
  915.       - It does not use initgraph, restorecrtmode, closegraph or setgraphmode
  916.         procedure. It simply assumes that appropriate graphic mode was
  917.         established before calling it.
  918.       - It is written in BGI independent way. That is it uses getmaxx,
  919.         getmaxy, getmaxcolor, getaspectratio to get device dependent
  920.         characteristic and scales all output according to it.
  921.       - Although it is not necessary it is recommended that it draws
  922.         the same picture (if the same BGI driver is used) each time
  923.         it is called.
  924.         This may be because if there is not enough memory to build bit image
  925.         map of the entire picture at once it is necessary to call
  926.         DrawFunc routine few times to create the picture piece by
  927.         piece (lines by lines). If it would draw different output at
  928.         consecutive calls then printed lines would not suit each other.
  929.       - It returns zero on success and nonzero on failure. This nonzero code
  930.         will cause immediate finish of the PRT_PrintBGI function and will
  931.         be also returned by it to the caller.
  932.       - It is declared as huge function if you are using C compiler.
  933.  
  934.  
  935.    Note also that if there is not enough free memory to build the whole
  936. bit image map at once then some graphic functions which read the
  937. screen explicitly (e.g. getpixel,getimage) or implicitly (e.g. floodfill) may
  938. produce inaccurate results. This may happen if they refer to currently
  939. not building part of the picture.
  940.    Setting PRT_HaltPrinting variable to nonzero value lets you break
  941. this function before it will finish.
  942.  
  943.  
  944.    PRT_PrintBuffer
  945.    ================
  946.  
  947. #if   C_only
  948. typedef int*   PRT__handleT;
  949. int  PRT_PrintBuffer (PRT__handleT *handlePtr);
  950. #endif   C_only
  951. #if   Pascal_only
  952. type    filePtr = ^file;
  953. Function PRT_PrintBuffer(var handlePtr: filePtr): integer;
  954. #endif   Pascal_only
  955.  
  956.    Prints entire "screen" buffer to the specified handle
  957. adding necessary control codes (see PRT_SetDriver).
  958.    To print out the buffer it uses PRT_Write function set by
  959. PRT_SetWriteFunc routine.
  960.    Note also that my standard PRT_Write function will call PRT_WriteError
  961. function (set by PRT_SetErrorFunc) whenever output error occurs.
  962.  
  963.    Returns 0 on success, nonzero on failure.
  964.  
  965. See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
  966. PRT_SetErrorFunc.
  967.  
  968.  
  969.    PRT_ReadDrivers
  970.    ===============
  971.  
  972. #if   C_only
  973. int  PRT_ReadDrivers
  974.      ( const char PRT__FAR_PTR* path, const char PRT__FAR_PTR* filename );
  975.  
  976. #endif
  977. #if   Pascal_only
  978. Type FnameStr = string[12];
  979. Function  PRT_ReadDrivers (path: DirStr; filename: FnameStr): integer;
  980. #endif
  981.  
  982.    Reads printers definitions from filename file at execution time.
  983. Path parameter may point to path containing printers definition file.
  984. You must use either PRT_LinkDrivers or PRT_ReadDrivers before
  985. any other function of this toolkit.
  986.    Returns zero on success.
  987.    See also PRT_LinkDrivers.
  988.  
  989.  
  990.    PRT_registerfarbgidriver
  991.    ========================
  992.  
  993. #if   C_only
  994. int PRT_registerfarbgidriver ( void far pascal
  995.                                                (*driver)(void) );
  996. #endif
  997. #if   Pascal_only
  998. Type DriverProc = procedure;
  999. PRT_registerbgidriver (  driver: DriverProc ): integer;
  1000. #endif
  1001.    To register BGI driver from the package use PRT_registerfarbgidriver
  1002. instead of standard  registerbgidriver or registerfarbgidriver function.
  1003. But note that before deleting registered driver from memory you
  1004. MUST use PRT_Unregisterfarbgidriver function.
  1005.  
  1006.  
  1007.    PRT_RescaleFillPattern
  1008.    =======================
  1009.  
  1010. #if   C_only
  1011. int PRT_RescaleFillPattern ( int r );
  1012. #endif   C_only
  1013. #if   Pascal_only
  1014. Function PRT_RescaleFillPattern ( r: integer ): integer;
  1015. #endif   Pascal_only
  1016.  
  1017.    Since external graphic devices have in most cases grater maximum
  1018. possible resolution than screens, standard 8x8 fill patterns seem to be
  1019. too small to use. This procedure let you demand of rescaling standard
  1020. 8x8 fill patterns to 16x16 ones.
  1021.    Parameter r means
  1022.          0 = never rescale to 16x16,
  1023.          1 = always rescale to 16x16,
  1024.          -1 = rescale to 16x16 at high densities only.
  1025.    The default value is -1.
  1026.    Returns 0 on success, nonzero on failure.
  1027.    If used must be called before initializing BITIMAGE BGI driver.
  1028.  
  1029.    See also setfillpattern16.
  1030.  
  1031.  
  1032.    PRT_Resolution
  1033.    ===============
  1034.  
  1035. #if   C_only
  1036. int  PRT_Resolution ( int FAR *Xres, int FAR *Yres );
  1037. #endif   C_only
  1038. #if   Pascal_only
  1039. Function PRT_Resolution ( var Xres,Yres : integer ): integer;
  1040. #endif   Pascal_only
  1041.  
  1042.    Assigns to Xres and Yres dpi (dots per inch) resolution in
  1043. appropriate direction according to last call of PRT_SetDriver.
  1044.    Returns 0 on success, nonzero on failure.
  1045.  
  1046.  
  1047.    PRT_Send
  1048.    ========
  1049.  
  1050. #if   C_only
  1051. int PRT_Send( const void far *p, unsigned slen);
  1052. #endif
  1053. #if   Pascal_only
  1054. Function PRT_Send( p: string): integer;
  1055. #endif
  1056.  
  1057.    Calls PRT_Open, PRT_Write, PRT_Close to send slen bytes
  1058. pointed to by p to the output file of a name set by PRT_SetOutName.
  1059.    Returns zero om success, nonzero on failure.
  1060. See also PRT_SetOutName, PRT_Open, PRT_Write, PRT_Close.
  1061.  
  1062.    PRT_SetBuffer
  1063.    ==============
  1064.  
  1065. #if   C_only
  1066. int PRT_SetBuffer ( long size, unsigned BufOpt );
  1067. #endif   C_only
  1068. #if   Pascal_only
  1069. Function PRT_SetBuffer ( size : longint; BufOpt: word ): integer;
  1070. #endif   Pascal_only
  1071.  
  1072.    Parameters
  1073.       BufOpt : specifies what kind of memory may be used for buffer.
  1074.                Allowed values.
  1075.                   NotUseEMS (1) - use XMS or conventional memory
  1076.                   NotUseXMS (2) - use EMS or conventional memory.
  1077.                   NotUseEMS+NotUseXMS - use conventional memory only.
  1078.                   0             - use any memory.
  1079.       size   : if positive specifies maximum amount of memory that
  1080.                can be used for the buffer.
  1081.                If negative specifies how minimum amount of memory that
  1082.                must be left free after buffer allocation.
  1083.                This parameter is currently meaningful only if conventional
  1084.                memory is used.
  1085.    Returns
  1086.       0 on success, nonzero on failure.
  1087.  
  1088.  
  1089.    PRINTBGI package uses the so called screen buffer to build bit
  1090. image map of printing output in it. This procedure specifies what kind
  1091. of memory can be used for that buffer. The whole buffer is allocated
  1092. in one kind of memory in the following priority order XMS, EMS,
  1093. conventional memory.
  1094.  
  1095.    If you have no particular need you should not call this procedure.
  1096. If not called PRINTBGI will behave as you call it with both parameters
  1097. zeroed thus enabling allocation of the buffer of the best size.
  1098.  
  1099.    If you let PRINTBGI to use EMS memory then keep in mind that DrawFunc
  1100. (set as parameter to PRT_PrintBGI) or any procedure called by it may not use
  1101. EMS memory.
  1102.    Note also that PRINTBGI does not save and restore EMS mapping at
  1103. any time. So if you want you can save EMS mapping before call of any
  1104. function that uses it and restore it afterwards. Following functions
  1105. may change EMS mapping: PRT_PrintBuffer, PRT_PrintBGI, PRT_BuildBitMap,
  1106. PRT_getpixel as well as any graphic routines using BitImage BGI driver.
  1107.  
  1108.    If used, must be called before initializing BITIMAGE BGI driver.
  1109.  
  1110. Try to use PRT_Buffer, PRT_EMSBuffer or PRT_XMSBuffer instead.
  1111.  
  1112.  
  1113.    PRT_SetCloseFunc
  1114.    =====================
  1115.  
  1116. #if   C_only
  1117.    typedef int ( FAR_PROC * PRT_CloseFuncP)( int* handle );
  1118. PRT_CloseFuncP PRT_SetCloseFunc ( int far f(int* handle) );
  1119. #endif   C_only
  1120. #if   Pascal_only
  1121.    Type CloseFuncType = Function(var handle:file): integer;
  1122. Function PRT_SetCloseFunc ( f: CloseFuncType ): CloseFuncType;
  1123. #endif   Pascal_only
  1124.  
  1125.    Defines function (passed as an argument f) which will be called to close
  1126. file handle used to print out the picture. The f function takes an integer*
  1127. argument which is supposed to contain an opened file handle. Exactly this is
  1128. the case if you do not specified your own open function. if you specified
  1129. your own open function the argument passed to close f function
  1130. contains a number returned from your open function (see PRT_SetOpenFunc).
  1131. This f function should return zero on success and suitable nonzero code
  1132. otherwise.
  1133.    If NULL is passed as an argument f then the old close function used so far
  1134. will not be changed.
  1135.    PRT_SetCloseFunc returns pointer to previously used close function.
  1136.  
  1137.    See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetErrorFunc.
  1138.  
  1139.  
  1140.    PRT_SetUserPrintFunc
  1141.    ====================
  1142.  
  1143. #if   C_only
  1144. typedef int PRT_UserPrintFuncT( void far* UserPtr,
  1145.                                      PRT__handleT   *handlePPtr,
  1146.                                 const char far* BGIpath);
  1147. PRT_UserPrintFuncT far *
  1148.      PRT_SetUserPrintFunc(PRT_UserPrintFuncT far* func);
  1149. #endif
  1150. #if   Pascal_only
  1151. Type
  1152.     PRT_UserPrintFuncT = function ( UserPtr:pointer;
  1153.                                               var handlePPtr: filePtr;
  1154.                                               BGIpath:PathStr ): integer;
  1155.     PRT_UserPrintFuncP = ^PRT_UserPrintFuncT;
  1156. Function PRT_SetUserPrintFunc (func:PRT_UserPrintFuncT): PRT_UserPrintFuncP;
  1157. #endif
  1158.  
  1159.    Ordinary after creating buffer with binary image of the picture
  1160. the PRT_PrintBuffer function is called. But to give you greater control
  1161. over what's doing I decided to let you define function which may be
  1162. called alternatively instead of PRT_PrintBuffer. And this is what
  1163. PRT_SetUserPrintFunc does. It enables you to define your own printing
  1164. function. In fact, to use some features, like screen preview (sorry,
  1165. this is not WYSIWYG) or printing in PCX format you must use
  1166. PRT_SetUserPrintFunc.
  1167.    Since writing your own printing function may not be very easy for
  1168. everyone I included examples of such functions in this package
  1169. (see UserPRTf.C, TVprtF.cpp  or  UserUnit.PAS).
  1170.  
  1171.  
  1172.    PRT_SetDriver
  1173.    ==============
  1174.  
  1175. #if   C_only
  1176. int PRT_SetDriver ( unsigned drv, unsigned mode,
  1177.                      unsigned width, unsigned height, unsigned options );
  1178. #endif   C_only
  1179. #if   Pascal_only
  1180. Function PRT_SetDriver ( drv,mode : word; width,height : word;
  1181.                           options: word ) : integer;
  1182. #endif   Pascal_only
  1183.  
  1184.  
  1185.    Parameters
  1186.       drv   : defines driver (and thus printer) number which will be
  1187.               used. Allowed values (See PRINTBGI.H or PRINTBGI.INT) are:
  1188.               IBM9, EPSON9, PANASONIC9, EPSON24, IBM24, HPLJII, HPPaintJet,
  1189.               LaserJet, PaintJet, IBM9c, EPSON9c, EPSON24c, IBM24c.
  1190.       mode  : defines driver (printer) mode number which will be
  1191.               used. Allowed values are defined in PRINTBGI.H
  1192.               (or PRINTBGI.INT for pascal version).
  1193.       width,height : defines width and height of the next printing
  1194.                      picture in 1/1000 inch values. That is 4000
  1195.                      means 4 inches.
  1196.       options      : can be defined as zero or it may have set one of the
  1197.                      following bits
  1198.          PRT_ROTATE  : if not set picture will be printed horizontally
  1199.                        if set picture will be printed vertically.
  1200.          PRT_INVERSE : if not set pixel of value 0 will be printed
  1201.                        as black and pixel of value 1 will be printed white.
  1202.                        1 means otherwise.
  1203.                        For color printers 1 will force bit negation
  1204.                        of pixel value before printing.
  1205.    Returns
  1206.       0 on success, nonzero on failure.
  1207.    Default values.
  1208.       Must be called. No default values assumed.
  1209.  
  1210.    Values defined by PRT_SetDriver stay in effect until next call of
  1211. that procedure changing them explicitly.
  1212.    Must be called before initializing BITIMAGE BGI driver. You must earlier
  1213. call PRT_LinkDrivers or PRT_ReadDrivers function.
  1214.    No checking is (or will be) made if specified values are correct for your
  1215. hardware. It is responsibility of the caller to detect hardware (or rather
  1216. ask user to define it) and specify picture size acceptable by it.
  1217.    See also PRT_SetPrinterDrv, PRT_SetPictureInch, PRT_SetPicturePix.
  1218.  
  1219.    PRT_SetErrorFunc
  1220.    =====================
  1221.  
  1222. #if   C_only
  1223.    typedef int ( FAR_PROC * PRT_ErrorFuncP) ( int* handle );
  1224. PRT_ErrorFuncP PRT_SetErrorFunc ( int WrErrFunc(int* handle) );
  1225. #endif   C_only
  1226. #if   Pascal_only
  1227.    Type ErrFuncType = Function ( var handle: file ): integer;
  1228. Function PRT_SetErrorFunc ( ErrFunc: ErrFuncType ): ErrFuncType;
  1229. #endif   Pascal_only
  1230.  
  1231.    Defines function (passed as an argument ErrFunc) which will be
  1232. called whenever I/O error occur during printing. ErrFunc must
  1233. return zero to retry printing or nonzero error code to abort
  1234. printing. In the second case the function in which an error occurred
  1235. returns immediately to the caller with the same return code as received
  1236. from ErrorFunc.
  1237.    If ErrFunc argument passed is NULL no ErrFunc will be called
  1238. whenever I/O error occurs.
  1239.    PRT_SetErrorFunc returns pointer to currently used ErrFunc.
  1240.  
  1241.  
  1242.    PRT_SetHaltVariable
  1243.    ===================
  1244.  
  1245. #if   C_only
  1246. void  PRT_SetHaltVariable(const byte far *haltVariable);
  1247. #endif   C_only
  1248. #if   Pascal_only
  1249. Procedure  PRT_SetHaltVariable(var haltVariable);
  1250. #endif   Pascal_only
  1251.  
  1252.    Defines so called halt variable. This variable must be set to zero
  1253. before starting printing. Setting haltVariable to any non zero during
  1254. printing process value will stop it.
  1255.  
  1256.  
  1257.    PRT_SetMargins
  1258.    ===============
  1259.  
  1260. #if   C_only
  1261. int PRT_SetMargins ( int left, int top );
  1262. #endif   C_only
  1263. #if   Pascal_only
  1264. Function PRT_SetMargins ( left,top : integer ) : integer;
  1265. #endif   Pascal_only
  1266.  
  1267.    Specifies (in 1/1000 inch) the left and top margins that should be
  1268. left free during printing. Note that in most cases real margins left will
  1269. be only some approximation of the specified values and may considerably
  1270. differ from them.
  1271.    Returns 0 on success, nonzero on failure.
  1272.  
  1273.  
  1274.    PRT_SetOpenFunc
  1275.    =====================
  1276.  
  1277. #if   C_only
  1278.    typedef int* ( FAR_PROC * PRT_OpenFuncP)( const char far*fname, int omode );
  1279. PRT_OpenFuncP PRT_SetOpenFunc ( int* far f(void) );
  1280. #endif   C_only
  1281. #if   Pascal_only
  1282.    Type PRT__FilePtr = ^file;
  1283.    Type OpenFuncType = Function PRT__FilePtr(var fname:PathStr;int omode): PRT__FilePtr;
  1284. Function PRT_SetOpenFunc ( f: OpenFuncType ): OpenFuncType;
  1285. #endif   Pascal_only
  1286.  
  1287.    Defines function (passed as an argument f) which will be called to open
  1288. file handle for printing out the picture. This f function takes two arguments:
  1289. file name and open mode. Open mode is defined as in C standard open function.
  1290. For pascal the only meaningfull bit is O_APPEND. If this bit is on file should
  1291. be opened in "append" mode, otherwise it should be opened in "truncated"
  1292. mode. Defined open function is used by PRT_WritePCX (in "truncated" mode)
  1293. and PRT_PrintBuffer (in "appended" mode). The new defined f function should
  1294. return as a result pointer to a opened file handle (or to a file in TP).
  1295. In case on failure it should return a pointer to a negative error code.
  1296.    Using PRT_SetOpenFunc you may define your own function used to open
  1297. file for output.
  1298.    If NULL is passed as an argument f then the old open function used so far
  1299. will not be changed.
  1300.    PRT_SetOpenFunc returns pointer to previously used open function.
  1301.  
  1302.    See also PRT_SetCloseFunc, PRT_SetWriteFunc, PRT_SetErrorFunc.
  1303.  
  1304.  
  1305.    PRT_SetOutName
  1306.    ==================
  1307.  
  1308. #if   C_only
  1309. int PRT_SetOutName ( const char FAR * DeviceName );
  1310. #endif   C_only
  1311. #if   Pascal_only
  1312. Function PRT_SetOutName ( DeviceName : string );
  1313. #endif   Pascal_only
  1314.  
  1315.    Specifies where the graphic output should be sent. DeviceName
  1316. can be any valid DOS device name (such as PRN,LPT1,LPT2,COM1, etc.)
  1317. or file name (with or without the path). It is used in pascal assign
  1318. procedure or C open function. Note that string pointed to by DeviceName
  1319. is not copied but only reference is remembered. So DeviceName should
  1320. not point to local dynamic area but to STATIC one rather.
  1321.    Returns 0 on success, nonzero on failure.
  1322.  
  1323.  
  1324.    PRT_SetPictureInch
  1325.    ==============
  1326.  
  1327. #if   C_only
  1328. int PRT_SetPictureInch ( unsigned width, unsigned height,
  1329.                          unsigned options );
  1330. #endif   C_only
  1331. #if   Pascal_only
  1332. int PRT_SetPictureInch ( unsigned width, unsigned height,
  1333.                          unsigned options );
  1334. #endif   Pascal_only
  1335.  
  1336.  
  1337.    Parameters
  1338.       width,height : defines width and height of the next printing
  1339.                      picture in 1/1000 inch values. That is 4000
  1340.                      means 4 inches.
  1341.       options      : see PRT_SetPictureInch for description of this
  1342.                      parameter.
  1343.  
  1344.    Returns
  1345.       0 on success, nonzero on failure.
  1346.  
  1347.    Must be called before initializing BITIMAGE BGI driver. You must earlier
  1348. call PRT_LinkDrivers or PRT_ReadDrivers function and PRT_SetPrinterDrv.
  1349.    No checking is (or will be) made if specified values are correct for your
  1350. hardware. It is responsibility of the caller to detect hardware (or rather
  1351. ask user to define it) and specify picture size acceptable by it.
  1352.    See also PRT_SetPrinterDrv, PRT_SetPictureInch.
  1353.  
  1354.  
  1355.    PRT_SetPicturePix
  1356.    ==============
  1357.  
  1358. #if   C_only
  1359. int PRT_SetPictureInch ( unsigned width, unsigned height,
  1360.                          unsigned options );
  1361. #endif   C_only
  1362. #if   Pascal_only
  1363. int PRT_SetPictureInch ( unsigned width, unsigned height,
  1364.                          unsigned options );
  1365. #endif   Pascal_only
  1366.  
  1367.  
  1368.    Parameters
  1369.       width,height : defines width and height of the next printing
  1370.                      picture in pixels values.
  1371.       options      : can be defined as zero or it may have set any of the
  1372.                      following bits
  1373.          PRT_ROTATE  : if not set picture will be printed horizontally
  1374.                        if set picture will be printed vertically.
  1375.          PRT_INVERSE : if not set pixel of value 0 will be printed
  1376.                        as black and pixel of value 1 will be printed white.
  1377.                        1 means otherwise.
  1378.                        For color printers 1 will force bit negation
  1379.                        of pixel value before printing.
  1380.                        To make picture rotated and inverse specify
  1381.                        PRT_ROTATE | PRT_INVERSE   for C
  1382.                        PRT_ROTATE or PRT_INVERSE   for Pascal.
  1383.    Returns
  1384.       0 on success, nonzero on failure.
  1385.  
  1386.    Must be called before initializing BITIMAGE BGI driver. You must earlier
  1387. call PRT_LinkDrivers or PRT_ReadDrivers function and PRT_SetPrinterDrv.
  1388.    No checking is (or will be) made if specified values are correct for your
  1389. hardware. It is responsibility of the caller to detect hardware (or rather
  1390. ask user to define it) and specify picture size acceptable by it.
  1391.    See also PRT_SetPrinterDrv, PRT_SetPicturePix.
  1392.  
  1393.  
  1394.    PRT_SetPrinterDrv
  1395.    ==============
  1396.  
  1397. #if   C_only
  1398. int PRT_SetPrinterDriver ( unsigned drv, unsigned mode);
  1399. #endif   C_only
  1400. #if   Pascal_only
  1401. Function PRT_SetPrinterDriver ( drv,mode : word ) : integer;
  1402. #endif   Pascal_only
  1403.  
  1404.  
  1405.    Parameters
  1406.       drv   : defines driver (and thus printer) number which will be
  1407.               used. Allowed values (See PRINTBGI.H or PRINTBGI.INT) are:
  1408.               IBM9, EPSON9, PANASONIC9, EPSON24, IBM24, HPLJII, HPPaintJet,
  1409.               LaserJet, PaintJet, IBM9c, EPSON9c, EPSON24c, IBM24c.
  1410.               Printer drivers are numbered starting from 1. Please do not
  1411.               use driver number 0. It is intended for future use. Use of it
  1412.               in current version will give you unpredictable results.
  1413.       mode  : defines driver (printer) mode number which will be
  1414.               used. Allowed values are defined in PRINTBGI.H
  1415.               (or PRINTBGI.INT for pascal version).
  1416.    Returns
  1417.       0 on success, nonzero on failure.
  1418.  
  1419.    Values defined by PRT_SetPrinterDrv stay in effect until next call of
  1420. that procedure changing them explicitly.
  1421.    Must be called before initializing BITIMAGE BGI driver. You must earlier
  1422. call PRT_LinkDrivers or PRT_ReadDrivers function. You must call
  1423. PRT_SetPictureInch or PRT_SetPicturePix to specify picture size.
  1424.    No checking is (or will be) made if specified values are correct for your
  1425. hardware. It is responsibility of the caller to detect hardware (or rather
  1426. ask user to define it) and specify picture size acceptable by it.
  1427.    See also PRT_SetDriver, PRT_SetPictureInch, PRT_SetPicturePix.
  1428.  
  1429.  
  1430.    PRT_SetViewSize
  1431.    ===============
  1432.  
  1433. #if   C_only
  1434. int PRT_SetViewSize( int x1, int y1, int x2, int y2 );
  1435. #endif
  1436. #if Pascal_only
  1437. Function PRT_SetViewSize( x1,y1, x2,y2: integer ): integer;
  1438. #endif
  1439.  
  1440. Parameters
  1441.    x1,y1,x2,y2 - specifies rectangular piece of picture which will be
  1442.                  built by the BitImage BGI driver.
  1443. See also PRT_initgraph.
  1444.  
  1445.  
  1446.    PRT_SetWriteFunc
  1447.    =====================
  1448.  
  1449. #if   C_only
  1450.    typedef int ( FAR_PROC * PRT_WriteFuncP)
  1451.                       ( int* handle, const void FAR_PTR * b, unsigned len );
  1452. PRT_WriteFuncP PRT_SetWriteFunc
  1453.                                ( int far f(int* handle,void FAR_PTR* buf,
  1454.                                  unsigned len) );
  1455. #endif   C_only
  1456. #if   Pascal_only
  1457.    Type WriteFuncType = Function(var handle:file; var b; len: word ): integer;
  1458. Function PRT_SetWriteFunc ( f: WriteFuncType ): WriteFuncType;
  1459. #endif   Pascal_only
  1460.  
  1461.    Defines function (passed as an argument f) which will be called to print
  1462. out len bytes pointed to by buf pointer.
  1463.    Parameters of f function
  1464.       handle  : an integer number returned by an open function set by
  1465.                 PRT_SetOpenFunc. My default open function simply returns
  1466.                 file handle.
  1467.       buf     : Pointer to data bytes which must be printed out.
  1468.       len     : Number of bytes to print.
  1469. If function f returns nonzero value it will be treated as an I/O error.
  1470.    If NULL is passed as an argument f then the old write function used so far
  1471. will be not changed.
  1472.    PRT_SetWriteFunc returns pointer to previously used write function.
  1473.  
  1474.    See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetErrorFunc.
  1475.  
  1476.  
  1477.  
  1478.    PRT_Unregisterfarbgidriver
  1479.    ========================
  1480.  
  1481. #if   C_only
  1482. int PRT_Unregisterfarbgidriver ( void far pascal
  1483.                                                  (*driver)(void) );
  1484. #endif
  1485. #if   Pascal_only
  1486. Type DriverProc = procedure;
  1487. PRT_Unregisterfarbgidriver (  driver: DriverProc ): integer;
  1488. #endif
  1489.  
  1490.    Used to unregister driver installed with PRT_registerfarbgidriver function.
  1491. You MUST use it before erasing registered BitImage driver from memory.
  1492.  
  1493.  
  1494.   PRT_Version
  1495.   ===========
  1496.  
  1497. #if   C_only
  1498. int PRT_Version(void);
  1499. #endif
  1500. #if   Pascal_only
  1501. Function PRT_Version integer;
  1502. #endif
  1503.  
  1504.    Returns toolkit major version on high byte and minor version number
  1505. on lower byte.
  1506.  
  1507.    PRT_XMSBuffer
  1508.    =============
  1509.  
  1510. #if   C_only
  1511. int PRT_XMSBuffer ( int handle, long size, int usable )
  1512. #endif
  1513. #if   Pascal_only
  1514. Function PRT_XMSBuffer ( handle: integer; size: longint; usable: integer ):
  1515.          integer;
  1516. #endif
  1517.    Defines XMS buffer for use by the PrintBGI package.
  1518.    Parameters:
  1519.       usable   :  0 (zero) means not to use XMS memory. Other arguments are
  1520.                   in that case ignored (but preferably should also be zero).
  1521.       handle   :  Number of XMM handle to use for the buffer or zero (buffer
  1522.                   will be allocated by the package)
  1523.       size     :  If handle is nonzero defines amount of memory (in bytes)
  1524.                   allocated to that handle by the caller.
  1525.                   If handle is zero then
  1526.                     -   positive value defines maximum number of memory (which
  1527.                         will be rounded down to 16 KB boundary) that can be
  1528.                         used for the buffer by PrintBGI package.
  1529.                     -   negative value defines minimum number of memory left
  1530.                         free after buffer allocation.
  1531.                     -   zero allows to allocate as much memory as needed for
  1532.                         the buffer leaving only absolutely minimum free.
  1533.  
  1534.       Note that XMS buffer requires also some conventional memory buffer to
  1535.    be allocated.
  1536.       See also PRT_Buffer,PRT_EMSBuffer.
  1537.  
  1538.  
  1539.     PRT_WritePCX
  1540.     ============
  1541. #if   C_only
  1542. typedef int*   PRT__handleT;
  1543. int PRT_WritePCX ( PRT__handleT *handlePtr )
  1544. #endif
  1545. #if   Pascal_only
  1546. type filePtr = ^file;
  1547. Function PRT_PrintBuffer(var handle: filePtr): integer;
  1548. #endif
  1549.  
  1550.    Prints entire "screen" buffer to the specified handle
  1551. in a PCX format. So the output should be directed rather to a file
  1552. than a real printer. You may later use a graphic program
  1553. to work with your picture. Note, I'm not sure all programs
  1554. will accept created PCX file, even if they are specified to do it.
  1555.    You cannot use it to create rotated pictures. Also if you specify
  1556. that you want inverse picture colors will be reversed.
  1557.    To print out the buffer it uses PRT_Write function set by
  1558. PRT_SetWriteFunc routine.
  1559.    Note also that my standard PRT_Write function will call PRT_WriteError
  1560. function (set by PRT_SetErrorFunc) whenever output error occurs.
  1561.    This function is never called by my code. To create PCX file you
  1562. must
  1563.  
  1564.    Returns 0 on success, nonzero on failure.
  1565.  
  1566. See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
  1567. PRT_SetErrorFunc.
  1568.  
  1569.  
  1570.    PRT_XMSBufferNeeded
  1571.    =================
  1572.  
  1573. #if   C_only
  1574. long PRT_XMSBufferNeeded ( int x1, int y1, int x2, int y2 );
  1575. #endif   C_only
  1576. #if   Pascal_only
  1577. Function PRT_XMSBufferNeeded ( x1,y1,x2,y2: integer ): longint;
  1578. #endif   Pascal_only
  1579.  
  1580.    Returns size of buffer needed to draw picture in XMS memory of specified
  1581. size and on printer set by PRT_SetDriver. The returned value will be somewhat
  1582. larger than that from PRT_BufferNeeded. If there exist less free memory than
  1583. needed then picture would be drawn in pieces. In that case results of all
  1584. procedures reading pixel values may be inaccurate.
  1585.    May be called only after PRT_SetDriver.
  1586.    See also PRT_EMSBufferNeeded, PRT_BufferNeeded.
  1587.  
  1588.  
  1589.    setcharsize_Pix
  1590.    ===============
  1591.  
  1592. #if  C_only
  1593. void  setcharsize_Pix (int width, int height);
  1594. #endif
  1595. #if   Pascal_only
  1596. Procedure  setcharsize_Pix ( width,height: integer );
  1597. #endif
  1598.  
  1599.    Sets char size width and height. The parameters should be given
  1600. in pixels. You may use it to obtain text proportional to the picture
  1601. sizes. For example if you want text height to be 1/60 of the whole
  1602. picture height and width 1/80 of the whole picture width you may use
  1603. following statement (in C language)
  1604.    setcharsize_Pix ( getmaxx()/80, getmaxy()/60 );
  1605.  
  1606.  
  1607.    setfillpattern16
  1608.    =================
  1609.  
  1610. #if   C_only
  1611. void setfillpattern16 ( char FAR * upattern, int color );
  1612. #endif   C_only
  1613. #if   Pascal_only
  1614. Procedure SetFillPattern16 ( upattern: FillPatternType; color: word );
  1615. #endif   Pascal_only
  1616.  
  1617.    If standard 8x8 fill patterns are not satisfied for you use this
  1618. function to define 16x16 patterns. Note that calling this function take
  1619. effect only when BITIMAGE BGI driver is active, for all other BGI drivers it
  1620. will be ignored. So the best approach is probably calling standard
  1621. setfillpattern function and then setfillpattern16. In that case ignoring
  1622. setfillpattern16 will cause that the pattern set by standard setfillpattern
  1623. function will be still in effect.
  1624.  
  1625.  
  1626.    PRT_HaltPrinting
  1627.    ================
  1628.  
  1629. Global variable. It is set to zero when PRT_PrintBGI starts. You may set it
  1630. to nonzero value to force almost immediate return from PRT_PrintBGI function
  1631. (without ending printing). This variable is tested after each line printed.
  1632. Note however that if PRT_PrintBGI called your Draw function then it will wait
  1633. for the Draw function to end before testing PRT_HaltPrinting.
  1634.    You may use PRT_SetHaltVariable function to specify different stop 
  1635. variable.
  1636.  
  1637.  
  1638.  
  1639. ========================================================================
  1640.          GRAPHIC   FUNCTIONS
  1641. ========================================================================
  1642.  
  1643.    This section will describe all graphics functions that can be found
  1644. in Borland Graph.TPU unit for TP or GRAPHICS.LIB for B/TC(++). Note
  1645. that detailed description of each function can be found in appropriate
  1646. Borland documentation. Here are only given some differences from their
  1647. use in PRINTBGI package and standard Borland BGI drivers.
  1648.  
  1649.    Following functions can be used with my BitImage BGI driver in the
  1650. same way as with standard Borland BGI drivers.
  1651.  
  1652.  
  1653. void far   arc(int x, int y, int stangle, int endangle, int radius);
  1654. void far   bar(int left, int top, int right, int bottom);
  1655. void far   bar3d(int left, int top, int right, int bottom,
  1656.                 int depth, int topflag);
  1657. void far   circle(int x, int y, int radius);
  1658. void far   clearviewport(void);
  1659. void far   drawpoly(int numpoints, int far *polypoints);
  1660. void far   ellipse(int x, int y, int stangle, int endangle,
  1661.                    int xradius, int yradius);
  1662. void far   fillellipse( int x, int y, int xradius, int yradius );
  1663. void far   fillpoly(int numpoints, int far *polypoints);
  1664. void far   getarccoords(struct arccoordstype far *arccoords);
  1665. void far   getaspectratio(int far *xasp, int far *yasp);
  1666. int  far   getbkcolor(void);
  1667. int  far   getcolor(void);
  1668. void far   getfillpattern(char far *pattern);
  1669. void far   getfillsettings(struct fillsettingstype far *fillinfo);
  1670. int  far   getgraphmode(void);
  1671. void far   getlinesettings(struct linesettingstype far *lineinfo);
  1672. int  far   getmaxcolor(void);
  1673. int  far   getmaxx(void);
  1674. int  far   getmaxy(void);
  1675. char * far getmodename( int mode_number );
  1676. void far   getpalette(struct palettetype far *palette);
  1677. int  far   getpalettesize( void );
  1678. void far   gettextsettings(struct textsettingstype far *texttypeinfo);
  1679. void far   getviewsettings(struct viewporttype far *viewport);
  1680. int  far   getx(void);
  1681. int  far   gety(void);
  1682. void far   graphdefaults(void);
  1683. char * far grapherrormsg(int errorcode);
  1684. void far   _graphfreemem(void far *ptr, unsigned size);
  1685. void far * far  _graphgetmem(unsigned size);
  1686. int  far   graphresult(void);
  1687. unsigned   far  imagesize(int left, int top, int right, int bottom);
  1688. int  far   installuserfont( char far *name );
  1689. void far   line(int x1, int y1, int x2, int y2);
  1690. void far   linerel(int dx, int dy);
  1691. void far   lineto(int x, int y);
  1692. void far   moverel(int dx, int dy);
  1693. void far   moveto(int x, int y);
  1694. void far   pieslice(int x, int y, int stangle, int endangle,
  1695.                     int radius);
  1696. void far   putimage(int left, int top, void far *bitmap, int op);
  1697. void far   putpixel(int x, int y, int color);
  1698. void far   rectangle(int left, int top, int right, int bottom);
  1699. int        registerbgifont (void (*font)(void));
  1700. int  far   registerfarbgifont (void far *font);
  1701. void far   sector( int X, int Y, int StAngle, int EndAngle,
  1702.                    int XRadius, int YRadius );
  1703. void far   setaspectratio( int xasp, int yasp );
  1704. void far   setcolor(int color);
  1705. void far   setfillpattern(char far *upattern, int color);
  1706. void far   setfillstyle(int pattern, int color);
  1707. unsigned far  setgraphbufsize(unsigned bufsize);
  1708. void far   setlinestyle(int linestyle, unsigned upattern,
  1709.                         int thickness);
  1710. void far   settextjustify(int horiz, int vert);
  1711. void far   setusercharsize(int multx, int divx,
  1712.                            int multy, int divy);
  1713. void far   setviewport(int left, int top, int right, int bottom,
  1714.                        int clip);
  1715. int  far   textheight(char far *textstring);
  1716. int  far   textwidth(char far *textstring);
  1717.  
  1718.  
  1719.    Following functions may differ somewhat when used with printer
  1720. devices. See short descritption after function declaration.
  1721.  
  1722.  
  1723. void far  cleardevice(void);
  1724.    Does not enforce printing. Buffer is cleared and if mot printed
  1725. earlier its content is lost forever.
  1726.  
  1727. void far  closegraph(void);
  1728.    You rather shouldn't use it with BitImage BGI driver. Use PRT_closegraph
  1729. instead.
  1730.  
  1731. void far  detectgraph(int far *graphdriver,int far *graphmode);
  1732.    It will return detect values for screen not for external devices.
  1733.  
  1734.  
  1735. void far  floodfill(int x, int y, int border);
  1736.    Not implemented in current release. It'll be implemented in future
  1737. releases but remember that may produce some inaccurate results if
  1738. there is less memory than needed to build whole bit map for the
  1739. picture. Compare with PRT_PrintBGI description. Note also that it
  1740. cannot be implemented for some kind of output devices.
  1741.  
  1742.  
  1743. struct palettetype far * far  getdefaultpalette( void );
  1744.    Not implemented.
  1745.  
  1746. char * far  getdrivername( void );
  1747.    Returns BGI driver name. Since the package uses always the
  1748. same BGI driver (called BITIMAGE BGI driver) it will always return
  1749. the word BITIMAGE. To obtain names of printer drivers supported call
  1750. PRT_DriverName function described in earlier section.
  1751.  
  1752. void far  getfillpattern(char far *pattern);
  1753.    See also getfillpattern16 and PRT_RescaleFillPattern.
  1754.  
  1755.  
  1756. void far  getimage( int left, int top, int right, int bottom,
  1757.                     void far *bitmap);
  1758.    May not work if there is not enough memory for the entire picture.
  1759. Otherwise is fully supported.
  1760.  
  1761. int  far  getmaxmode(void);
  1762.    You should use rather PRT_MaxMode instead. Currently it always
  1763. returns zero since BitImage BGI driver being used supports one mode
  1764. only. Parameters which configure the driver for your needs can be set
  1765. using PRT_SetDriver function.
  1766.  
  1767.  
  1768. int  far  getmaxx(void);
  1769.    You should use it to rescale output according to screen sizes.
  1770.  
  1771. int  far  getmaxy(void);
  1772.    You should use it to rescale output according to screen sizes.
  1773.  
  1774. void far  getmoderange(int graphdriver, int far *lomode,
  1775.          int far *himode);
  1776.    Shouldn't be used.
  1777.  
  1778. unsigned   far  getpixel(int x, int y);
  1779.    May not work if there is not enough memory for the entire picture.
  1780. Otherwise is fully supported.
  1781.  
  1782. char * far  grapherrormsg(int errorcode);
  1783.    You may use PRT_grapherrormsg instead.
  1784.  
  1785. void far  initgraph(int  far *graphdriver,
  1786.             int  far *graphmode,
  1787.             char far *pathtodriver);
  1788.    To initialize BitImage BGI driver you must use PRT_initgraph instead.
  1789.  
  1790. int  far  installuserdriver( char far *name, int huge (*detect)(void) );
  1791.    You must use PRT_installuserdriver to install PRINTBGI drivers.
  1792.  
  1793. void far  outtext(char far *textstring);
  1794.    To print standard fonts of code 128 or higher you should use DOS
  1795. GrafTabl command before, otherwise printing is garbage. Note also
  1796. that fonts table for characters 127 or lower is taken from ROM BIOS.
  1797. If you have no such a table in standard place some problems may also
  1798. occur.
  1799.    See also settextstyle comments.
  1800.  
  1801. void far  outtextxy(int x, int y, char far *textstring);
  1802.    See outtext and settextstyle comments.
  1803.  
  1804.  
  1805. int         registerbgidriver (void (*driver)(void));
  1806.    To register BitImage driver you should use PRT_registerfarbgidriver
  1807. instead.
  1808.  
  1809. int   far   registerfarbgidriver (void far *driver);
  1810.    To register BitImage driver you should use PRT_registerfarbgidriver
  1811. instead.
  1812.  
  1813. void far  restorecrtmode(void);
  1814.    Shouldn't be used. Before using PrintBGI toolkit functions you must
  1815. close down any active video BGI driver. To do this use closegraph not
  1816. restorecrtmode function. On the other hand using restorecrtmode with
  1817. BitImage BGI driver has little sense.
  1818.  
  1819. void far  setactivepage(int page);
  1820.    Not implemented.
  1821.  
  1822. void far  setallpalette(struct palettetype far *palette);
  1823.    Not implemented.
  1824.  
  1825. void far  setaspectratio( int xasp, int yasp );
  1826.    You may use it to change current aspect ratio but remember that
  1827. default values are correct.
  1828.  
  1829. void far  setbkcolor(int color);
  1830.    Not implemented in current release.
  1831.  
  1832. void far  setfillpattern(char far *upattern, int color);
  1833.    See setfillpattern16 and PRT_RescaleFillPattern in previous section.
  1834.  
  1835. void far  setfillstyle(int pattern, int color);
  1836.    See PRT_RescaleFillPattern in previous section.
  1837.  
  1838. void far  setgraphmode(int mode);
  1839.    Shouldn't be used.
  1840.  
  1841. void far  setpalette(int colornum, int color);
  1842.    Not implemented.
  1843.  
  1844. void far  setrgbpalette(int colornum,
  1845.           int red, int green, int blue);
  1846.    Not implemented.
  1847.  
  1848. void far  settextstyle(int font, int direction, int charsize);
  1849.    May produce different results for standard fonts (DEFAULT_FONT)
  1850. and direction other than HORIZ_DIR or VERT_DIR. May also behave
  1851. slightly different when text expands beyond clip region. You may use
  1852. setcharsize_Pix function to set font size in pixels.
  1853.  
  1854. void far  setvisualpage(int page);
  1855.    Not implemented.
  1856.  
  1857. void far  setwritemode( int mode );
  1858.    In difference with Borland's BGI drivers write mode defined by
  1859. that procedure is valid for all subsequent write operations. Mode
  1860. argument may be one of the following: COPYPUT, XORPUR, ORPUT,
  1861. AND_PUT, NOT_PUT not just limited to fist two constants only (as is
  1862. in Borland's library).
  1863.  
  1864.  
  1865.  
  1866.       DEFINING YOUR OWN PRINTERS
  1867.       ==========================
  1868.  
  1869.    Printers descriptions used by the package are contained in Drivers
  1870. module. I included in this package all files necessary to compile
  1871. Drivers.ASM. So you may modify this file and compile it creating OBJ file
  1872. which in turn you should added to PRTGRAPH.LIB replacing old OBJect member
  1873. of the same name. Turbo Pascal users should compile Drivers.Pas file
  1874. instead of modifying PRTGRAPH.LIB.
  1875.    I must tell you that defining your own printer is not easy. You probably
  1876. will have a lot of troubles with it unless you are an expert in using
  1877. printers in graphic mode. In that case you should not have troubles. Read
  1878. Drivers.INC and then copy one of the closest printer already defined in
  1879. Drivers.ASM and modify parameters you need.
  1880.    I suppose there are some printers which cannot be added this way. If you
  1881. have such a one it means that it requires the modification of printers
  1882. definitions structure as well as some other source code modifications.
  1883. Please contact the author in that case.
  1884.  
  1885.  
  1886.       THE FUTURE
  1887.       ==========
  1888.  
  1889.    If there is some interest in this package I will write 1.0 version
  1890. which will
  1891.    - support all dot matrix printers, postscript printers and some
  1892.      others as well as some plotters,
  1893.    - contain table (and function to use it) with names of all available
  1894.      printers and appropriate driver number used by the package (if users
  1895.      support me in doing it) ,
  1896.    - let you keep printers definitions in separate file or linked it with
  1897.      the main module,
  1898.    - work in all memory models (except tiny of course),
  1899.    - be tested on more printers,
  1900.    - contain some more improvements, I hope.
  1901. All registered users will obtain this 1.0 version completely free.
  1902.  
  1903.  
  1904. To contact the author write to
  1905.  
  1906.    Andrzej Resztak
  1907.    ul. K. Wallenroda 2c/18
  1908.    20-607 Lublin
  1909.    POLAND
  1910.  
  1911. or (preferably) to e-mail address:
  1912.    Resztak@PLUMCS11.bitnet
  1913.  
  1914.  
  1915.    /* end of FUNCTION.DOC  */
  1916.  
  1917.  
  1918.